<!DOCTYPE html>
<!--
 | Generated by Apache Maven Doxia Site Renderer 1.11.1 from src/site/markdown/usage.md at 2024-05-26
 | Rendered using Apache Maven Fluido Skin 1.7
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="Date-Revision-yyyymmdd" content="20240526" />
    <meta http-equiv="Content-Language" content="en" />
    <title>org.panteleyev:jpackage-maven-plugin &#x2013; Usage</title>
    <link rel="stylesheet" href="./css/apache-maven-fluido-1.7.min.css" />
    <link rel="stylesheet" href="./css/site.css" />
    <link rel="stylesheet" href="./css/print.css" media="print" />
    <script type="text/javascript" src="./js/apache-maven-fluido-1.7.min.js"></script>
  </head>
  <body class="topBarDisabled">
    <div class="container-fluid">
      <div id="banner">
        <div class="pull-left"><div id="bannerLeft"><h2>org.panteleyev:jpackage-maven-plugin</h2>
</div>
</div>
        <div class="pull-right"></div>
        <div class="clear"><hr/></div>
      </div>

      <div id="breadcrumbs">
        <ul class="breadcrumb">
        <li id="publishDate">Last Published: 2024-05-26<span class="divider">|</span>
</li>
          <li id="projectVersion">Version: 1.6.4</li>
        </ul>
      </div>
      <div class="row-fluid">
        <div id="leftColumn" class="span2">
          <div class="well sidebar-nav">
    <ul class="nav nav-list">
      <li class="nav-header">Overview</li>
    <li><a href="index.html" title="Introduction"><span class="none"></span>Introduction</a></li>
    <li><a href="plugin-info.html" title="Goals"><span class="none"></span>Goals</a></li>
    <li class="active"><a href="#"><span class="none"></span>Usage</a></li>
      <li class="nav-header">Examples</li>
    <li><a href="examples/full-jre.html" title="Image with full JRE"><span class="none"></span>Image with full JRE</a></li>
    <li><a href="examples/executions.html" title="Configuration with executions"><span class="none"></span>Configuration with executions</a></li>
    <li><a href="examples/profiles.html" title="Configuration with profiles"><span class="none"></span>Configuration with profiles</a></li>
      <li class="nav-header">Project</li>
    <li><a href="summary.html" title="Summary"><span class="none"></span>Summary</a></li>
    <li><a href="scm.html" title="Source"><span class="none"></span>Source</a></li>
    <li><a href="dependencies.html" title="Dependencies"><span class="none"></span>Dependencies</a></li>
</ul>
          <hr />
          <div id="poweredBy">
            <div class="clear"></div>
            <div class="clear"></div>
            <div class="clear"></div>
            <div class="clear"></div>
<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="./images/logos/maven-feather.png" /></a>
            </div>
          </div>
        </div>
        <div id="bodyColumn"  class="span10" >
<section>
<h2><a name="Usage"></a>Usage</h2>
<p>For detailed information about <code>jpackage</code> please refer to
<a class="externalLink" href="https://docs.oracle.com/en/java/javase/22/jpackage/packaging-tool-user-guide.pdf">Packaging Tool User's Guide</a>.</p><section>
<h3><a name="Finding_jpackage"></a>Finding jpackage</h3>
<p>Plugin searches for <code>jpackage</code> executable using the following priority list:</p>
<ol style="list-style-type: decimal">

<li>

<p><code>maven-toolchains-plugin</code> configured in the project. Toolchain &#x201c;jdk&#x201d; will be queried for
tool = &#x201c;jpackage&#x201d;.</p>
</li>
<li>

<p><code>java.home</code> system property.</p>
</li>
</ol></section><section>
<h3><a name="Configuration"></a>Configuration</h3>
<p>There are generic parameters as well as OS-specific parameters for OS X and Windows.
Plugin determines OS name using <code>os.name</code> system property in order to configure OS-specific parameters.</p>
<p>Generic parameters should be placed in the root plugin configuration. OS-specific parameters should be separated with
executions or profiles.</p>
<p>See examples:</p>
<ul>

<li><a href="./examples/executions.html">Configuration with executions</a></li>
<li><a href="./examples/profiles.html">Configuration with profiles</a></li>
</ul><section>
<h4><a name="Mandatory_Parameters"></a>Mandatory Parameters</h4>
<p>To enable various configuration approaches mandatory parameters are validated during plugin execution:</p>
<ul>

<li>name</li>
<li>destination</li>
</ul></section><section>
<h4><a name="Relative_Path_Resolution"></a>Relative Path Resolution</h4>
<p>The following plugin parameters define directory or file location:</p>
<ul>

<li>destination</li>
<li>icon</li>
<li>input</li>
<li>installDir</li>
<li>resourceDir</li>
<li>modulePath</li>
<li>runtimeImage</li>
<li>appImage</li>
<li>temp</li>
<li>licenseFile</li>
<li>launcher.file</li>
<li>appContentPath</li>
<li>macEntitlements</li>
<li>macDmgContentPath</li>
</ul>
<p>If path is not absolute is will be resolved as relative to <code>${project.basedir}</code>.</p>
<p>One exception is <code>installDir</code> which is passed as is.</p></section><section>
<h4><a name="Java_Options"></a>Java Options</h4>
<p>&lt;javaOptions&gt; defines options for JVM running the application. Each option should be specified in a separate
&lt;option&gt; tag.</p>
<p><i>Example:</i></p>

<div class="source"><pre class="prettyprint"><code class="language-xml">&lt;javaOptions&gt;
    &lt;javaOption&gt;--enable-preview&lt;/javaOption&gt;
    &lt;javaOption&gt;-Dfile.encoding=UTF-8&lt;/javaOption&gt;
    &lt;javaOption&gt;--add-export&lt;/javaOption&gt;
    &lt;javaOption&gt;java.base/sun.security.util=ALL-UNNAMED&lt;/javaOption&gt;
&lt;/javaOptions&gt;
</code></pre></div></section><section>
<h4><a name="Default_Command-Line_Arguments"></a>Default Command-Line Arguments</h4>
<p>Default command line arguments are passed to the main class when the application is started without providing arguments.
Each argument should be specified using &lt;argument&gt; configuration parameter.</p>
<p><i>Example:</i></p>

<div class="source"><pre class="prettyprint"><code class="language-xml">&lt;arguments&gt;
    &lt;argument&gt;SomeArgument&lt;/argument&gt;
    &lt;argument&gt;Argument with spaces&lt;/argument&gt;
    &lt;argument&gt;Argument with &quot;quotes&quot;&lt;/argument&gt;
&lt;/arguments&gt;
</code></pre></div></section><section>
<h4><a name="Additional_Launchers"></a>Additional Launchers</h4>
<p>Additional launchers provide the opportunity to install alternative ways to start an application.</p>
<p><i>Example:</i></p>

<div class="source"><pre class="prettyprint"><code class="language-xml">&lt;launchers&gt;
    &lt;launcher&gt;
        &lt;name&gt;App1&lt;/name&gt;
        &lt;file&gt;src/resources/App1.properties&lt;/file&gt;
    &lt;/launcher&gt;
    &lt;launcher&gt;
        &lt;name&gt;App2&lt;/name&gt;
        &lt;file&gt;src/resources/App2.properties&lt;/file&gt;
    &lt;/launcher&gt;
&lt;/launchers&gt;
</code></pre></div></section><section>
<h4><a name="File_Associations"></a>File Associations</h4>
<p>If you want your application to be started when a user opens a specific type of file, use <code>&lt;fileAssociations&gt;</code>
configuration.</p>
<p><i>Example:</i></p>

<div class="source"><pre class="prettyprint"><code class="language-xml">&lt;fileAssociations&gt;
    &lt;fileAssociation&gt;src/properties/java.properties&lt;/fileAssociation&gt;
    &lt;fileAssociation&gt;src/properties/cpp.properties&lt;/fileAssociation&gt;
&lt;/fileAssociations&gt;
</code></pre></div>
<p>Note: apparently this option does not work for modular applications.</p></section><section>
<h4><a name="jlink_options"></a>jlink options</h4>
<p>Options that are passed to underlying jlink call.</p>
<p><i>Example:</i></p>

<div class="source"><pre class="prettyprint"><code class="language-xml">&lt;jLinkOptions&gt;
    &lt;jLinkOption&gt;--strip-native-commands&lt;/jLinkOption&gt;
    &lt;jLinkOption&gt;--strip-debug&lt;/jLinkOption&gt;
&lt;/jLinkOptions&gt;
</code></pre></div></section><section>
<h4><a name="Additional_JPackage_Options"></a>Additional JPackage Options</h4>
<p>Additional options allow passing jpackage command line options not supported by the plugin. These options are passed as is without any transformation.</p>
<p><i>Example:</i></p>

<div class="source"><pre class="prettyprint"><code class="language-xml">&lt;additionalOptions&gt;
    &lt;option&gt;--jlink-options&lt;/option&gt;
    &lt;option&gt;--bind-services&lt;/option&gt;
&lt;/additionalOptions&gt;
</code></pre></div></section></section><section>
<h3><a name="Assembling_Dependencies"></a>Assembling Dependencies</h3>
<p>Before executing <code>jpackage</code> all runtime dependencies should be copied into a single folder together with main
application jar. This example shows how to do this via <code>maven-dependency-plugin</code>.</p>

<div class="source"><pre class="prettyprint"><code class="language-xml">&lt;plugins&gt;
    &lt;plugin&gt;
        &lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt;
        &lt;artifactId&gt;maven-jar-plugin&lt;/artifactId&gt;
        &lt;configuration&gt;
            &lt;outputDirectory&gt;target/jmods&lt;/outputDirectory&gt;
        &lt;/configuration&gt;
    &lt;/plugin&gt;
    
    &lt;plugin&gt;
        &lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt;
        &lt;artifactId&gt;maven-dependency-plugin&lt;/artifactId&gt;
        &lt;executions&gt;
            &lt;execution&gt;
                &lt;id&gt;copy-dependencies&lt;/id&gt;
                &lt;phase&gt;package&lt;/phase&gt;
                &lt;goals&gt;
                    &lt;goal&gt;copy-dependencies&lt;/goal&gt;
                &lt;/goals&gt;
                &lt;configuration&gt;
                    &lt;includeScope&gt;runtime&lt;/includeScope&gt;
                    &lt;outputDirectory&gt;target/jmods&lt;/outputDirectory&gt;
                &lt;/configuration&gt;
            &lt;/execution&gt;
        &lt;/executions&gt;
    &lt;/plugin&gt;

    &lt;plugin&gt;
        &lt;groupId&gt;org.panteleyev&lt;/groupId&gt;
        &lt;artifactId&gt;jpackage-maven-plugin&lt;/artifactId&gt;
        &lt;configuration&gt;
            &lt;modulePaths&gt;
                &lt;modulePath&gt;target/jmods&lt;/modulePath&gt;
            &lt;/modulePaths&gt;
        &lt;/configuration&gt;
    &lt;/plugin&gt;
&lt;/plugins&gt;
</code></pre></div></section></section><section>
<h2><a name="Dry_Run_Mode"></a>Dry Run Mode</h2>
<p>To print jpackage parameters without executing jpackage set <code>jpackage.dryRun</code> property to <code>true</code>.</p>
<p><i>Example:</i></p>

<div class="source"><pre class="prettyprint"><code>mvn clean package jpackage:jpackage@win -Djpackage.dryRun=true
</code></pre></div></section>
        </div>
      </div>
    </div>
    <hr/>
    <footer>
      <div class="container-fluid">
        <div class="row-fluid">
Copyright (c) 2020-2024, Petr Panteleyev
        </div>
      </div>
    </footer>
  </body>
</html>
